home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / -archivi / -recent2 / gaplib.lha / GAPLib_Beta / utility / report.doc < prev    next >
Text File  |  1999-03-13  |  4KB  |  183 lines
  1. TABLE OF CONTENTS
  2.  
  3. report/--background--
  4. report/--format--
  5. report/DoReport
  6. report/EndReport
  7. report/MakeReport
  8.  
  9.  
  10. report/--background--                                     report/--background--
  11.  
  12.    PURPOSE
  13.     To enable easy generation of data files for GAP-Lib.
  14.  
  15.    OVERVIEW
  16.     Report generation utility code for GAP-Lib.
  17.  
  18.     The report utility package consists of three functions, one to
  19.     initialize a report structure, one to write data to any report files
  20.     and one to free resources allocated by the other two functions. The
  21.     useage should be fairly obvious and the function and format descriptions
  22.     will now follow after just one further ado.
  23.  
  24.    EXAMPLE
  25.     This example outlines the useage of the report function, in this
  26.     case two report files will be generated - "example.avg" and
  27.     "example.max".
  28.  
  29.     Example code:
  30.  
  31.     #include <GAP.h>
  32.     #include "report.h"
  33.  
  34.     int main(void)
  35.     {
  36.     struct Report *Rep;
  37.     struct Population *Pop;
  38.     ...
  39.        Rep = MakeReport("example");
  40.        if(Rep!=NULL) {
  41.        ...
  42.           Pop = Evolve(Pop,Tags);
  43.           DoReport(Rep,Pop,AVERAGE|MAX);
  44.        ...
  45.           EndReport(Rep);
  46.        }
  47.     ...
  48.     }
  49.  
  50. report/--format--                                             report/--format--
  51.  
  52.    OVERVIEW
  53.     The data format output by DoReport() is indeed very simple. It consists
  54.     of two columns of data in human-readable form. The first column is the
  55.     generation and the second the data value itself. Furthermore, at the
  56.     top of each file there is a one line comment describing the content of
  57.     the columns.
  58.        The reason for choosing this format is one one hand that it is
  59.     simple to work with, and on the other hand to be compatible with
  60.     gnuplot.
  61.  
  62.    DESCRIPTION
  63.     The data format is as follows (Well, actually the format for TypeCount
  64.     is <Integer> <Integer>, but it does not hurt to treat it as double):
  65.  
  66.     #Generation, <Data>
  67.     <Integer> <Double>
  68.     ...
  69.     ...
  70.     <Integer> <Double>
  71.  
  72.    EXAMPLE
  73.     Sample datafile:
  74.  
  75.     #Generation, Average
  76.     1 28.23554
  77.     2 29.45442
  78.     3 31.13943
  79.     4 31.64233
  80.     5 31.88642
  81.     6 33.19521
  82.     7 35.16777
  83.     8 35.74699
  84.     9 36.77469
  85.     10 37.45532
  86.  
  87. report/EndReport                                               report/EndReport
  88.  
  89.    NAME
  90.     EndReport -- Free a report structure.
  91.  
  92.    SYNOPSIS
  93.     void EndReport(struct Report *);
  94.  
  95.     EndReport(Rep);
  96.  
  97.    FUNCTION
  98.     Frees all resources associated with a report structure and flushes
  99.     output.
  100.  
  101.    INPUTS
  102.     Rep    - The report structure to be deallocated.
  103.  
  104.    RESULT
  105.     None.
  106.  
  107.    BUGS
  108.     None known.
  109.  
  110.    SEE ALSO
  111.     MakeReport(), DoReport()
  112.  
  113. report/DoReport                                                 report/DoReport
  114.  
  115.    NAME
  116.     DoReport -- Write report data from a population structure.
  117.  
  118.    SYNOPSIS
  119.     void DoReport(struct Report *,struct Population *,unsigned long int);
  120.  
  121.     DoReport(Rep,Pop,Flags);
  122.  
  123.    FUNCTION
  124.     Writes poulation data to a set of report files.
  125.  
  126.    INPUTS
  127.     Rep    - The report structure in question.
  128.     Pop    - The population to retrieve the data from.
  129.     Flags    - A set of flags which determine which data to write.
  130.           Available flags are:
  131.  
  132.            AVERAGE   - Average fitness.
  133.            MEDIAN    - Median fitness.
  134.            TYPECOUNT - Count of most common fitness value.
  135.            STDDEV    - Standard Deviation.
  136.            MAX       - Maximum fitness.
  137.            MIN       - Minimum fitness.
  138.            ALL       - All the above.
  139.  
  140.           Flags are combined by OR:ing them together and e.g.
  141.           AVERAGE|MAX would mean write average and maximum fitness
  142.           to the report files.
  143.  
  144.    RESULT
  145.     None.
  146.  
  147.    BUGS
  148.     None known.
  149.  
  150.    SEE ALSO
  151.     MakeReport(), EndReport()
  152.  
  153.  
  154. report/MakeReport                                             report/MakeReport
  155.  
  156.    NAME
  157.     MakeReport -- Initialize a report structure and return it.
  158.  
  159.    SYNOPSIS
  160.     struct Report *MakeReport(char *);
  161.  
  162.     Rep = MakeReport(Basename);
  163.  
  164.    FUNCTION
  165.     This function will initialize a report structure and open
  166.     report files for writing. Basename is the first part of the
  167.     filenames used for the data. The actual filenames are formed by
  168.     appending a suitable suffix to the basename such as ".max" for
  169.     maximum fitness data.
  170.  
  171.    INPUTS
  172.     Basename   - The main part of the names of the report files.
  173.  
  174.    RESULT
  175.     An initialized report structure or NULL if an error occured.
  176.  
  177.    BUGS
  178.     None known.
  179.  
  180.    SEE ALSO
  181.     DoReport(), EndReport()
  182.  
  183.